.\" t
.TH "cldaemonctl" "1M" "Jun 23, 2006" "1\&.2\&.0"
.SH NAME
cldaemonctl \- Pass messages to Linuxha.net Cluster Daemon

.SH SYNOPSIS
.TS
l.
cldaemonctl \fB-M|--msg\fP \fImsg\fP [\fB-V|--verbose\fP] [\fB--nochecksums\fP]
       Pass message to Cluster Daemon

cldaemonctl \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
This utility allows the administrator to send a message to the Linuxha.net
cluster daemon. It can be run on either node in the cluster and it will 
communicate to any node currently running as part of the cluster, 
(though it will always try connecting to the local node first).

Once the message has been dealt with by the cluster daemon the output will 
be sent to the standard output. The message may consist one or more lines 
of output, depending on the request.

.SH WARNING
As with the \fIlemsctl(1M)\fP utility this routine has been written for
administrators with significant experience and knowledge of the product. It 
is not recommended that you use this tool unless you are comfortable with 
what it is capable of doing - such as failing-over applications, or stopping
communication channels, reseting machines and fail-over characteristics etc.

.SH COMMON MESSAGES
The number of messages that can be sent to the daemon is significant,
though most are only recommended under exceptional conditions. The section
below describes some of the more common requests for version 1.2.0. For a
full list please see the Administrators Guide.

.TP 4
.B HELP
Returns a list of commands that the daemon is able to accept. Only the 
command name is shown, not the mandatory or optional arguments, which
is scheduled for inclusion for later releases.

.TP
\fBLOGCYCLE\fP count=N
When running in verbose mode, (which is recommended), the cluster daemon is
likely to generate a significant amount of output over time. Since it
keeps the log file open for writing at all times, management of such files
is not straightfiorward.

Fortunatetely this command is available and it will stop writing to the
current log file, cycle it, (i.e. add a ".1" extension), and then
resume writing to a new file. Existing cycled log files are kept upto a
maximum number of iterations specified on the command line, (which can be
up to 99).

.TP
\fBABORT\fP [forward=yes]
Indicates that the cluster daemon should abort on the daemon that received
the request. If the "forward=yes" option is specified the request will also
be sent to the remote daemon.

.TP
\fBGETVALIDNODES\fP app=name
Returns a comma separated list of nodes that are currently valid for the
specified application. If a software failure occurs and a fail-over of an
application is requested unless the other node is in this list the fail-over
will be aborted and the application stopped instead.

.TP
\fBSETVALIDNODES\fP app=name [nodes=a[,b]]
Allows the list of nodes to which an application can fail-over to be to
modified. If the "nodes" argument is not present then it will be reset to
include both nodes. If the argument is present then either zero, one or
noth nodes can be specified, comma separated.

It should be noted the \fIclset(1M)\fP utility provides this functionality
in a more convenient manner.

.TP
\fBISVALID\fP app=name
This returns OK if the node that receives the request is currently considered
a valid node to run the specified application.

.TP
\fBSTOP_APP\fP app=name
If the specified application is running in the cluster then it should be
stopped.

.TP
\fBFAILOVER\fP app=name
If the specified application is running stop it on the node it is currently
running on and attempt to start it on the other node in the cluster. Please
note that if the other node is not running, or is not a valid node for the
application the application will stop on its current node, but not start
on the alternative node.

.TP
\fBAPP_STATUS\fP app=name [lvinfo=yes|failoverinfo=yes]
This allows you to query the status of a particular application. The optional
"lvinfo" or "failoverinfo" may be supplied to produce further details. For 
information on the format of the output with or without the optional
arguments please see the Administrators guide for details.

.TP
\fBCHANGE_DSTATE\fP state=UP|DOWN|PARTITIONED
This changes the current node status - this is used as part of the cluster
formation process. Making use of this command directly is discouraged.

.TP
\fBAPP_UPDATE\fP app=APP [node=N] [forward=yes
This allows the dynamic state of the specified application to be changed.
Apart from the \fBapp\fP argument all other arguments are optional. The
currently support optional arguments include \fBnode\fP which can be used to
indicate where the application is running; \fBstate\fP to change the application
status [to 'STARTED' for example]; \fBforward\fP to cause the specified changes
to be propagated to the other node; \fBstarttime\fP to indicate when the 
specified application started and finally \fBmonitor\fP [set to '0' or '1' to
indicate whether a Lems session is running.

.TP
\fBAPP_LIST\fP
This returns the list of currently registered applications in the cluster. An
application can only be started if it is currently registered.

.TP
\fBTOC\fP
Immediately reset the local server - use when handling split brain recovery.

.TP
\fBSWAP_APPS\fP
When this occurs all applications that were registered as running on the \fBother\fP 
node in the cluster are forced to start on \fBthis\fP node. This message is sent
by the heartbeat daemon if it believes the remote node has died.

.TP
\fBRECONFIGURE\fP
This is sent whenever the cluster is rebuilt using \fBclbuild(1M)\fP. It causes the
local cluster daemon to re-read its XML configuration file and where possible 
respond to any changes that the running daemon makes use of.

Almost all changes are taken account of, apart from the following;

.TS
l.
* server_port
* server_key
* drbd_network
* nodes
.TE

.TP
\fBAPPS_RUNNING\fP apps=N,...
The nodes pass this message between themselves on a regular basis when in
communication. This information is used when recovery from a partitioned cluster
to indicate which, if any, node should be TOC'd.

.SH ARGUMENTS
Only three options are currently supported by this utility:

.TP 8
.B --verbose
Gives some output to the standard output regarding the operation of the
command - nothing of any real detail is currently produced, however.
.TP
.B --msg
The message to send to the running daemon. The response will be sent to the
standard output.
.TP
.B --nochecksums
Normally if the cluster configuration file has been modified whilst the 
cluster is running the checksum which is used to indicate the last sane and 
checked configuration will not be valid. In such instances many of the 
Linuxha.net commands, including this will not will not function. 
If necessary the \fB--nochecksums\fP can be used to overcome this until the 
cluster configuration can be re-checked.

.SH EXIT STATUS
The \fIcldaemonctl(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the message was
past to the Lems daemon and the response was returned.

Please note that if the command "failed" on the cluster daemon but it managed
to send a response then the \fIcldaemonctl(1M)\fP will return a successful
exit code.

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build / Validate cluster topology
clbuildapp(1M)	- Build / Synchronise cluster application 
clform(1M)	- Cluster formation utility
clstat(1M)	- Show cluster status information
cldeamon(1M)	- Cluster status Daemon
clrunapp(1M)	- High level application start-up
clstartapp(1M)	- Start a clustered application
clhaltapp(1M)	- Halt a clustered application
lemsctl(1M)	- Send message to Lems daemon
clconf.xml(5)	- Overall cluster topology configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH AUTHOR
The \fIcldaemonctl(1M)\fP utility was written by Simon Edwards, 2004-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

